🔍 The embarrassing truth about our (internal) feature documentation! 🤯

As the lead behind the points-based rewards system in Germany (Pluspunkte) and across Europe, I often face questions from business teams about our system's features. Being in this space for quite a long time, I typically have a good grasp of the features. …and then they ask for details 😱

Now we have to look them up in the source code as our feature documentation is - …limited. It is rather an architecture documentation and a list of features, and we avoided details on purpose as documentation and implementation typically get out of sync over time.

...and the documentation is just for us developers, isn’t it??? 🤦

This not only takes quite a long time and hence is not really efficient—it also risks our credibility with other teams.

But there is a solution in the pipeline!

Our system has a huge suite of acceptance tests which get executed as part of the unit tests (yes, that fast!). These tests are written in Gherkin notation, so “given - when - then” and are based on the Java BDD library JGiven. They describe the features in great details and with examples and offer a promising path. By converting JGiven's JSON report into a markdown file structure through a custom tool, we can seamlessly feed it into our Docusaurus documentation project.

Exciting, right? 🤔

Do you have a better idea on how to create detailed feature documentation that doesn’t get out of sync over time? Please share your thoughts in the comments.

Let's discuss!

Please let's discuss on LinkedIn.